Patch Deployment Templates

When deploying patches to machines, patch deployment templates allow you to specify a number of different options. For example, you can specify whether the deployment target should be restarted after the deployment, how fast the patches should be copied to the remote machines, whether reports should be sent, and much more.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}

 

Success or failure code.

You cannot delete a predefined template.

GET

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

URL Parameters

PatchDeploymentTemplates[]

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template guid}

 

PatchDeployTemplate

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions

 

CustomActions[]

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions/{custom action id}

 

CustomAction

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/usedby

 

Usedby[]

POST

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

Request Body

 

Input Models

Name Type Description

count

Integer

Provide the count of items to return. The default is 10 and the maximum value is 1000.

createdByMe

Boolean

Returns only those items created by the user.

This parameter will be removed in a future release and should only be used in legacy requests.

name

String

Returns the items whose name matches the specified name.

start

Integer

Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.

path

String

Sets the path and is used to find templates matching the specified path.
Name Required? Type Default Value Description

description

No

String

None

Gets or sets the description.

distributionServerOptions

No

DistributionServerOptions

 

The options corresponding to the Distribution Servers tab of the deployment template.

generalOptions

No

DeployGeneralOptions

 

The options corresponding to the General tab of the deployment template.

name

Yes

String

None

Gets or sets the name.

path

No

String

None

Gets or sets the path.

postDeploymentReboot

No

PostDeployReboot

 

The options corresponding to the Post-deploy Reboot tab of the deployment template.

preDeploymentReboot

No

PreDeployReboot

 

The options corresponding to the Pre-deploy Reboot tab of the deployment template.

virtualOptions

No

VirtualMachineAndTemplate
Options

 

The options corresponding to the Hosted VMs/Templates tab of the deployment template.

Example with Sample Response

Create a patch deployment template named "Sample"

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

Request Body

{"Name":"Sample","Description":"A sample deployment template created using the REST API"}

Sample Response

Copy 
{
    "creator": "SHAVLIK\\joe.coder",
    "description": "A sample deployment template created using the REST API",
    "generalOptions": {
        "removeTempFiles": false,
        "sendTrackerMessages": true,
        "shutdownIis": false,
        "shutdownSql": false
    },
    "id": "9b5d4668-48fa-41ed-b424-094e6922a11b",
    "isSystem": false,
    "isTemporary": false,
    "links": {
        "customactions": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/customactions"
        },
        "self": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b"
        },
        "usedby": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/usedby"
        }
    },
    "name": "Sample",
    "postDeploymentReboot": {
        "options": {
            "powerState": "Restart",
            "countdownMinutes": 5,
            "extendMinutes": 1,
            "forceActionAfterMinutes": 10,
            "loggedOnUserAction": "ForceActionAfterMinutes",
            "systemDialogSeconds": 60,
            "userOptions": "AllowExtension"
        },
        "when": "Immediate"
    },
    "preDeploymentReboot": {
        "when": "NoReboot"
    },
    "virtualOptions": {
        "takePostDeploymentSnapshots": false,
        "takePreDeploymentSnapshots": false
    }
}

Other Request Examples

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/01234567-89AB-CDEF-0123-456789ABCDEF

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/2ecc2474-8142-4e2b-8a16-eabf6e43086c

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/2ecc2474-8142-4e2b-8a16-eabf6e43086c/customactions

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/01234567-89AB-CDEF-0123-456789ABCDEF/usedby

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates

{ name: "Example5", PreDeploymentReboot = @{ When ='Immediate'; Options = @{ LoggedOnUserAction = 'ForceActionAfterMinutes'; ForceActionAfterMinutes=15; extendMinutes = 1; userOptions='AllowExtension, AllowCancelTimeout, AllowCancelReboot' } }; }

Output Models

Name Type Description

creator

String

The creator.

description

String

Gets or sets the description.

distributionServerOptions

DistributionServerOptions

The options corresponding to the Distribution Servers tab of the deployment template.

generalOptions

DeployGeneralOptions

The options corresponding to the General tab of the deployment template.

id

Guid

Gets or sets the patch deployment template UID.

isSystem

Boolean

Gets or sets the flag indicating if this is a system template.

isTemporary

Boolean

Indicates that this is temporary and can be deleted after the deployment.

links

Links

Shows the related URLs for the patch deployment template, the custom actions and the usedby list.

name

String

Gets or sets the name.

path

String

Gets or sets the path.

postDeploymentReboot

PostDeployReboot

The options corresponding to the Post-deploy Reboot tab of the deployment template.

preDeploymentReboot

PreDeployReboot

The options corresponding to the Pre-deploy Reboot tab of the deployment template.

virtualOptions

VirtualMachineAndTemplate
Options

The options corresponding to the Hosted VMs/Templates tab of the deployment template.
Name Type Description

hoursUntilEmailSent

Integer

Indicates how many hours to wait for patches to be successfully deployed before sending any automatic email messages.

remoteDialogConfig

RemoteDialogConfig

The options corresponding to the Remote Dialog section on the General tab of the deployment template.

removeTempFiles

Boolean

Indicates if the temporary patch files that were copied during the deployment process will be removed.

sendTrackerMessages

Boolean

Indicates if Deployment Tracker status messages will be sent from the machines being patched.

shutdownIis

Boolean

Indicates if the IIS Server will be shut down before the patch deployment process begins.

shutdownSql

Boolean

Indicates if the SQL Server will be shut down before the patch deployment process begins.
Name Type Description

caption

String

Specifies the text you want to appear in the Remote dialog caption.

title

String

Specifies the text you want to appear in the Remote dialog box title.
Name Type Description

byIpRange

Boolean

Indicates if the distribution server that will be used will be determined by the IP address of each target machine. You must have defined one or more IP ranges and assigned the ranges to a primary distribution server and to a backup server.

defaultId

Integer

The default distribution server ID when UseSpecificServer is specified.

errorRetry

RelayErrorRetry[]

Specifies when to try again if no patch can be retrieved from the distribution server.

fallbackToVendorSite

Boolean

If the distribution server is not available, the machine being patched will attempt to download the patch files from the patch vendor's website.

staggerStartTime

Integer

Stagger distribution server download times in minutes.
Name Type Description

none

String

A retry will not be attempted and the deployment will fail.

atReboot

String

A retry will be attempted each time the target machine is rebooted, for up to three reboots.

periodic

String

A retry will be attempted at 15, 30, 60 and 120 minute intervals after the initial failure, and again when the target machine is rebooted. Retries are also attempted after two subsequent reboots.
Name Type Description

options

PostDeployRebootOptions

Specifies the reboot options.

when

RebootWhenOption

Specifies when the reboot will occur.
Name Type Description

options

DeployRebootOptions

Specifies the reboot options.

when

RebootWhenOption

Specifies when the reboot will occur.
Name Type Description

earliestTime

DateTime

The earliest time the safe reboot action can occur.

powerState

TargetPowerState

The target power state after deployment is complete.

Enables you to specify what state you want to leave the machines after the reboot. The items in this table are mutually exclusive; you can only specify one option.

Name Type Description

stayOnline

String

The machines are kept in their current state.

sleep

String

The machines are put into sleep mode.

hibernate

String

The machines are put into a hibernation mode.

shutdown

String

The machines are powered off without being restarted.

restart

String

The machines are restarted and left in a powered on state.

restartThenSleep

String

The machines are restarted and then put into sleep mode.

restartThenHibernate

String

The machines are restarted and then put into a hibernation state.

restartThenShutdown

String

The machines are restarted and then powered off.
Name Type Description

noReboot

String

Do not reboot the machine after patch deployment.

immediate

String

Reboot the machine immediately after deployment.

scheduledTime

String

Reboot the machine at the next occurrence of the scheduled time.

scheduledDateTime

String

Reboot the machine at the scheduled date and time.

immediateIfRequired

String

Reboot the machine immediately, but only if required.

scheduledTimeIfRequired

String

Reboot the machine at the scheduled time, but only if required.

scheduledDateTimeIfRequired

String

Reboot the machine at the scheduled date and time, but only if required.
Name Type Description

countDownMinutes

Integer

The countdown minutes.

extendMinutes

Integer

The number of minutes a user is allowed to extend the countdown.

forceActionAfterMinutes

Integer

The number of minutes before the safe reboot option action will occur.

forceActionOnLatestTime

DateTime

The latest time the safe reboot action will occur.

loggedOnUserAction

LoggedOnUserAction[]

The action to take if a user is logged on.

systemDialogSeconds

Integer

The number of seconds the system dialog will display during shutdown.

userOptions

RebootInteractionOptions[]

The options a user is allowed to do during the safe reboot action.

If you elect to restart machines, you can specify the degree of control the user will have over the restart process. These are flags, so you can add several of them at once in an array.

Name Description

none

The user will have no control over the restart process.

allowExtension

Allow the user to extend the time-out countdown up to a specified maximum.

allowCancelTimeout

Allow the user to cancel the time-out. The patches will not be deployed until the user manually restarts the machine.

allowCancelReboot

Allow the user to cancel the reboot. The patches will not be installed until the machine is restarted.

allowNoTimeout

 

noRestart

 

If you elect to restart machines, you can specify the amount of warning that a logged-on user will receive.

Name Description

alertUser

Alert the user that a restart will occur when they log off.

forceActionAfterMinutes

Force a restart after a number of minutes have passed.

forceActionOn

Force a restart at a specific date and time.
Name Type Description

maxSnapshotCount

Integer

The maximum snapshot count to manage.

oldestSnapshotInDays

Integer

The number of days a snapshot will be allowed to exist.

takePostDeploymentSnapshots

Boolean

Indicates if a snapshot will be taken of the offline virtual machine after deploying missing patches or service packs.

takePreDeploymentSnapshots

Boolean

Indicates if a snapshot will be taken of the virtual machine prior to deploying missing patches or service packs.
Name Type Description

actionType

CustomDeploymentAction[]

Specifies the action type.

command

String

The location of the .exe file that is to be executed.

id

Integer

The unique identifier of this CustomAction object.

kb

String

The KB number.

links

Links

Shows the related URLs

patchActedOn

String

The patch that will be acted on during installation.

Specifies when during the patch deployment process the custom command will be triggered.

Name Description

push

Pushes a custom batch file or custom executable file to the target machines as part of the deployment.

first

Before any patches are installed.

before

Before each patch or service pack is installed.

after

After each patch or service pack is installed.

last

After all patches are installed (but before reboot)

reboot

After the reboot.
Name Type Description

name

String

The name of the item using the template.

usageType

Enum

The type of component using the template.